---
title: Secrets
description: Store and retrieve sensitive data in workflows.
icon: key
---

import SecretsExample from '/snippets/secrets-example.mdx'
import SecretsUsage from '/snippets/secrets-usage.mdx'

Tracecat comes with a build-in secrets manager.
This allows you to store and retrieve sensitive data without exposing the value in plaintext.
Secrets are encrypted at rest and stored in the database.

## Storing secrets

Secrets are scoped to a workspace. To add a secret, navigate to the **Credentials** page and click on the **Create Secret** button.

<SecretsExample />

## `SECRETS` context

<SecretsUsage />

## Integrations and secrets

<Tip>
    Check out the [integrations](/cheatsheets/integrations) cheatsheet for a list of pre-built integrations and their required secrets.
</Tip>

Authentication with pre-built integrations is handled implicitly.

Pre-built integrations are associated with specific secret names and keys.
For example, the VirusTotal integration requires a secret with the name `virustotal` and the key `VIRUSTOTAL_API_KEY`.

Different integrations may require different required and optional keys.
For example, Tracecat's AWS integration is configured with the following secret with optional keys, but with `optional=False` meaning at least one of the keys must be provided:

```python
aws_secret = RegistrySecret(
    name="aws",
    optional_keys=[
        # Access key-based authentication
        "AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY",
        "AWS_REGION",
        # Role-based authentication
        "AWS_ROLE_ARN",
        "AWS_ROLE_SESSION_NAME",
        # Profile-based authentication
        "AWS_PROFILE_NAME",
    ]
    optional=False
)
```

## OAuth secrets

Unlike regular secrets, OAuth secrets are not stored in the secrets manager. Instead, they are stored in the OAuth provider's database.
To access them use the following syntax:

```php
${{ SECRETS.<provider_id>_oauth.<prefix>_[SERVICE|USER]_TOKEN }}
```

For example, to access the GitHub user token, you would use the following expression:

```php
${{ SECRETS.github_oauth.GITHUB_USER_TOKEN }}
```

OAuth secrets are scoped to a provider. To add an OAuth secret, navigate to the **Integrations** page and click on the **Create OAuth Secret** button.

<OAuthSecretsExample />

## Multi-tenant secrets

A common use case is to have different sets of the same secret for different tenants.
For example, an MDR provider will likely have different Crowdstrike tenant IDs for each customer.

Tracecat supports multi-tenant secrets via the workflow's `environment` configuration.

**Example**

<Steps>
  <Step title="Create a multi-tenant secret">
    Create a multi-tenant secret for an integration by specifying the environment key.
    The secret name and keys (e.g. `aws` and `AWS_ROLE_ARN`) remain the same.

    If no environment key is specified, the environment key defaults to `default`.

    ![Specify environment for secret](/img/quickstart/secrets/multi-tenant-secret.png)
  </Step>
<Step title="Specify workflow environment">
    Click on the workflow canvas. You can specify the workflow's environment under the `Configuration` section.

    ![Specify workflow environment](/img/quickstart/secrets/workflow-environment.png)
  </Step>
  <Step title="Trigger multi-tenant workflows">
    Let's say you have multiple sets of AWS credentials, one for each account, and you want to retrieve GuardDuty detections for each account.

    You can do this easily in two-steps using a looped `core.workflow.execute` action.

    First, drag out a `core.workflow.execute` action, then specify a loop expression that iterates over a list of AWS account IDs:

    ```yaml
    ${{ for var.aws_account_id in <some-list-of-account-ids> }}
    ```

    ![Loop expression](/img/quickstart/secrets/loop-expression.png)

    Then configure the `core.workflow.execute` action with the following inputs:

    ```yaml
    trigger_inputs: <child-workflow-inputs>
    workflow_alias: <child-workflow-alias>  # You can find this in the workflows page
    environment: ${{ var.aws_account_id }}  # The secret environment
    ```

    ![Execute child workflow with variable environment](/img/quickstart/secrets/child-workflow.png)
  </Step>
</Steps>
